home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / Kubuntu 8.10 / kubuntu-8.10-desktop-i386.iso / casper / filesystem.squashfs / usr / share / perl5 / Mail / Internet.pod < prev    next >
Text File  |  2008-04-14  |  11KB  |  516 lines
  1. =head1 NAME
  2.  
  3. Mail::Internet - manipulate email messages
  4.  
  5. =head1 INHERITANCE
  6.  
  7. =head1 SYNOPSIS
  8.  
  9.   use Mail::Internet;
  10.   my $msg = Mail::Internet->new(\*STDIN);
  11.  
  12. =head1 DESCRIPTION
  13.  
  14. This package implements reading, creating, manipulating, and writing email
  15. messages.  Sometimes, the implementation tries to be too smart, but in
  16. the general case it works as expected.
  17.  
  18. If you start writing a B<new application>, you should use the L<Mail::Box>
  19. distribution, which has more features and handles messages much better
  20. according to the RFCs.  See L<http://perl.overmeer.net/mailbox/>.
  21. You may also chose L<MIME::Entity>, to get at least some multipart
  22. support in your application.
  23.  
  24. =head1 METHODS
  25.  
  26. =head2 Constructors
  27.  
  28. $obj-E<gt>B<dup>
  29.  
  30. =over 4
  31.  
  32. Duplicate the message as a whole.  Both header and body will be
  33. deep-copied: a new L<Mail::Internet|Mail::Internet> object is returned.
  34.  
  35. =back
  36.  
  37. $obj-E<gt>B<extract>(ARRAY-of-LINES)
  38.  
  39. =over 4
  40.  
  41. Extract header and body from an ARRAY of message lines.  Requires an
  42. object already created with L<new()|Mail::Internet/"Constructors">, which contents will get overwritten.
  43.  
  44. =back
  45.  
  46. $obj-E<gt>B<new>([ARG], [OPTIONS])
  47.  
  48. Mail::Internet-E<gt>B<new>([ARG], [OPTIONS])
  49.  
  50. =over 4
  51.  
  52. ARG is optional and may be either a file descriptor (reference to a GLOB)
  53. or a reference to an array. If given the new object will be
  54. initialized with headers and body either from the array of read from 
  55. the file descriptor.
  56.  
  57. The L<Mail::Header::new()|Mail::Header/"Constructors"> OPTIONS C<Modify>, C<MailFrom> and C<FoldLength>
  58. may also be given.
  59.  
  60.  Option--Default
  61.  Body    []
  62.  Header  undef
  63.  
  64. . Body => ARRAY-of-LINES
  65.  
  66. =over 4
  67.  
  68. The value of this option should be a reference to an array which contains
  69. the lines for the body of the message. Each line should be terminated with
  70. C<\n> (LF). If Body is given then C<Mail::Internet> will not attempt to
  71. read the body from C<ARG> (even if it is specified).
  72.  
  73. =back
  74.  
  75. . Header => Mail::Header
  76.  
  77. =over 4
  78.  
  79. The value of this option should be a L<Mail::Header|Mail::Header> object. If given then
  80. C<Mail::Internet> will not attempt to read a mail header from C<ARG>, if
  81. it was specified.
  82.  
  83. =back
  84.  
  85. =back
  86.  
  87. $obj-E<gt>B<read>(FILEHANDLE)
  88.  
  89. =over 4
  90.  
  91. Read a message from the FILEHANDLE into an already existing message
  92. object.  Better use L<new()|Mail::Internet/"Constructors"> with the FILEHANDLE as first argument.
  93.  
  94. =back
  95.  
  96. =head2 Accessors
  97.  
  98. $obj-E<gt>B<body>([BODY])
  99.  
  100. =over 4
  101.  
  102. Returns the body of the message. This is a reference to an array.
  103. Each entry in the array represents a single line in the message.
  104.  
  105. If I<BODY> is given, it can be a reference to an array or an array, then
  106. the body will be replaced. If a reference is passed, it is used directly
  107. and not copied, so any subsequent changes to the array will change the
  108. contents of the body.
  109.  
  110. =back
  111.  
  112. $obj-E<gt>B<head>
  113.  
  114. =over 4
  115.  
  116. Returns the C<Mail::Header> object which holds the headers for the current
  117. message
  118.  
  119. =back
  120.  
  121. =head2 Processing the message as a whole
  122.  
  123. $obj-E<gt>B<as_mbox_string>([ALREADY_ESCAPED])
  124.  
  125. =over 4
  126.  
  127. Returns the message as a string in mbox format.  C<ALREADY_ESCAPED>, if
  128. given and true, indicates that L<escape_from()|Mail::Internet/"High-level functionality"> has already been called on
  129. this object.
  130.  
  131. =back
  132.  
  133. $obj-E<gt>B<as_string>
  134.  
  135. =over 4
  136.  
  137. Returns the message as a single string.
  138.  
  139. =back
  140.  
  141. $obj-E<gt>B<print>([FILEHANDLE])
  142.  
  143. =over 4
  144.  
  145. Print the header, body or whole message to file descriptor I<FILEHANDLE>.
  146. I<$fd> should be a reference to a GLOB. If I<FILEHANDLE> is not given the
  147. output will be sent to STDOUT.
  148.  
  149. example: 
  150.  
  151.     $mail->print( \*STDOUT );  # Print message to STDOUT
  152.  
  153. =back
  154.  
  155. $obj-E<gt>B<print_body>([FILEHANDLE])
  156.  
  157. =over 4
  158.  
  159. Print only the body to the FILEHANDLE (default STDOUT).
  160.  
  161. =back
  162.  
  163. $obj-E<gt>B<print_header>([FILEHANDLE])
  164.  
  165. =over 4
  166.  
  167. Print only the header to the FILEHANDLE (default STDOUT).
  168.  
  169. =back
  170.  
  171. =head2 Processing the header
  172.  
  173. Most of these methods are simply wrappers around methods provided
  174. by L<Mail::Header|Mail::Header>.
  175.  
  176. $obj-E<gt>B<add>(PAIRS-of-FIELD)
  177.  
  178. =over 4
  179.  
  180. The PAIRS are field-name and field-content.  For each PAIR,
  181. L<Mail::Header::add()|Mail::Header/"Processing"> is called.  All fields are added after
  182. existing fields.  The last addition is returned.
  183.  
  184. =back
  185.  
  186. $obj-E<gt>B<combine>(TAG, [WITH])
  187.  
  188. =over 4
  189.  
  190. See L<Mail::Header::combine()|Mail::Header/"Processing">.
  191.  
  192. =back
  193.  
  194. $obj-E<gt>B<delete>(TAG, [TAGs])
  195.  
  196. =over 4
  197.  
  198. Delete all fields with the name TAG.  L<Mail::Header::delete()|Mail::Header/"Processing"> is doing the
  199. work.
  200.  
  201. =back
  202.  
  203. $obj-E<gt>B<fold>([LENGTH])
  204.  
  205. =over 4
  206.  
  207. See L<Mail::Header::fold()|Mail::Header/"Processing">.
  208.  
  209. =back
  210.  
  211. $obj-E<gt>B<fold_length>([TAG], [LENGTH])
  212.  
  213. =over 4
  214.  
  215. See L<Mail::Header::fold_length()|Mail::Header/"Accessors">.
  216.  
  217. =back
  218.  
  219. $obj-E<gt>B<get>(TAG, [TAGs])
  220.  
  221. =over 4
  222.  
  223. In LIST context, all fields with the name TAG are returned.  In SCALAR
  224. context, only the first field which matches the earliest TAG is returned.
  225. L<Mail::Header::get()|Mail::Header/"Processing"> is called to collect the data.
  226.  
  227. =back
  228.  
  229. $obj-E<gt>B<header>([ARRAY-of-LINES])
  230.  
  231. =over 4
  232.  
  233. See L<Mail::Header::header()|Mail::Header/""Fake" constructors">.
  234.  
  235. =back
  236.  
  237. $obj-E<gt>B<replace>(PAIRS-of-FIELD)
  238.  
  239. =over 4
  240.  
  241. The PAIRS are field-name and field-content.  For each PAIR,
  242. L<Mail::Header::replace()|Mail::Header/"Processing"> is called with INDEX 0. If a FIELD is already
  243. in the header, it will be removed first.  Do not specified the same
  244. field-name twice.
  245.  
  246. =back
  247.  
  248. =head2 Processing the body
  249.  
  250. $obj-E<gt>B<remove_sig>([NLINES])
  251.  
  252. =over 4
  253.  
  254. Attempts to remove a users signature from the body of a message. It does this 
  255. by looking for a line equal to C<'-- '> within the last C<NLINES> of the
  256. message. If found then that line and all lines after it will be removed. If
  257. C<NLINES> is not given a default value of 10 will be used. This would be of
  258. most use in auto-reply scripts.
  259.  
  260. =back
  261.  
  262. $obj-E<gt>B<sign>(OPTIONS)
  263.  
  264. =over 4
  265.  
  266. Add your signature to the body.  L<remove_sig()|Mail::Internet/"Processing the body"> will strip existing
  267. signatures first.
  268.  
  269.  Option   --Default
  270.  File       undef
  271.  Signature  []
  272.  
  273. . File => FILEHANDLE
  274.  
  275. =over 4
  276.  
  277. Take from the FILEHANDLE all lines starting from the first C<< -- >>.
  278.  
  279. =back
  280.  
  281. . Signature => STRING|ARRAY-of-LINES
  282.  
  283. =back
  284.  
  285. $obj-E<gt>B<tidy_body>
  286.  
  287. =over 4
  288.  
  289. Removes all leading and trailing lines from the body that only contain
  290. white spaces.
  291.  
  292. =back
  293.  
  294. =head2 High-level functionality
  295.  
  296. $obj-E<gt>B<escape_from>
  297.  
  298. =over 4
  299.  
  300. It can cause problems with some applications if a message contains a line
  301. starting with C<`From '>, in particular when attempting to split a folder.
  302. This method inserts a leading C<`>'> on anyline that matches the regular
  303. expression C</^>*From/>
  304.  
  305. =back
  306.  
  307. $obj-E<gt>B<nntppost>([OPTIONS])
  308.  
  309. =over 4
  310.  
  311. Post an article via NNTP.  Requires Net::NNTP to be installed.
  312.  
  313.  Option--Default
  314.  Debug   <false>
  315.  Host    <required>
  316.  Port    119
  317.  
  318. . Debug => BOOLEAN
  319.  
  320. =over 4
  321.  
  322. Debug value to pass to Net::NNTP, see L<Net::NNTP>
  323.  
  324. =back
  325.  
  326. . Host => HOSTNAME|Net::NNTP object
  327.  
  328. =over 4
  329.  
  330. Name of NNTP server to connect to, or a Net::NNTP object to use.
  331.  
  332. =back
  333.  
  334. . Port => INTEGER
  335.  
  336. =over 4
  337.  
  338. Port number to connect to on remote host
  339.  
  340. =back
  341.  
  342. =back
  343.  
  344. $obj-E<gt>B<reply>(OPTIONS)
  345.  
  346. =over 4
  347.  
  348. Create a new object with header initialised for a reply to the current 
  349. object. And the body will be a copy of the current message indented.
  350.  
  351. The C<.mailhdr> file in your home directory (if exists) will be read
  352. first, to provide defaults.
  353.  
  354.  Option  --Default
  355.  Exclude   []
  356.  Indent    '>'
  357.  Keep      []
  358.  ReplyAll  false
  359.  
  360. . Exclude => ARRAY-of-FIELDS
  361.  
  362. =over 4
  363.  
  364. Remove the listed FIELDS from the produced message.
  365.  
  366. =back
  367.  
  368. . Indent => STRING
  369.  
  370. =over 4
  371.  
  372. Use as indentation string.  The string may contain C<%%> to get a single C<%>,
  373. C<%f> to get the first from name, C<%F> is the first character of C<%f>,
  374. C<%l> is the last name, C<%L> its first character, C<%n> the whole from
  375. string, and C<%I> the first character of each of the names in the from string.
  376.  
  377. =back
  378.  
  379. . Keep => ARRAY-of-FIELDS
  380.  
  381. =over 4
  382.  
  383. Copy the listed FIELDS from the original message.
  384.  
  385. =back
  386.  
  387. . ReplyAll => BOOLEAN
  388.  
  389. =over 4
  390.  
  391. Automatically include all To and Cc addresses of the original mail,
  392. excluding those mentioned in the Bcc list.
  393.  
  394. =back
  395.  
  396. =back
  397.  
  398. $obj-E<gt>B<send>([TYPE, [ARGS...]])
  399.  
  400. =over 4
  401.  
  402. Send a Mail::Internet message using L<Mail::Mailer|Mail::Mailer>.  TYPE and ARGS are
  403. passed on to L<Mail::Mailer::new()|Mail::Mailer/"Constructors">.
  404.  
  405. =back
  406.  
  407. $obj-E<gt>B<smtpsend>([OPTIONS])
  408.  
  409. =over 4
  410.  
  411. Send a Mail::Internet message using direct SMTP.  to the given
  412. ADDRESSES, each can be either a string or a reference to a list of email
  413. addresses. If none of C<To>, <Cc> or C<Bcc> are given then the addresses
  414. are extracted from the message being sent.
  415.  
  416. The return value will be a list of email addresses that the message was sent
  417. to. If the message was not sent the list will be empty.
  418.  
  419. Requires Net::SMTP and Net::Domain to be installed.
  420.  
  421.  Option  --Default
  422.  Bcc       undef
  423.  Cc        undef
  424.  Debug     <false>
  425.  Hello     localhost.localdomain
  426.  Host      $ENV{SMTPHOSTS}
  427.  MailFrom  Mail::Util::mailaddress()
  428.  Port      25
  429.  To        undef
  430.  
  431. . Bcc => ADDRESSES
  432.  
  433. . Cc => ADDRESSES
  434.  
  435. . Debug => BOOLEAN
  436.  
  437. =over 4
  438.  
  439. Debug value to pass to Net::SMPT, see <Net::SMTP>
  440.  
  441. =back
  442.  
  443. . Hello => STRING
  444.  
  445. =over 4
  446.  
  447. Send a HELO (or EHLO) command to the server with the given name.
  448.  
  449. =back
  450.  
  451. . Host => HOSTNAME
  452.  
  453. =over 4
  454.  
  455. Name of the SMTP server to connect to, or a Net::SMTP object to use
  456.  
  457. If C<Host> is not given then the SMTP host is found by attempting
  458. connections first to hosts specified in C<$ENV{SMTPHOSTS}>, a colon
  459. separated list, then C<mailhost> and C<localhost>.
  460.  
  461. =back
  462.  
  463. . MailFrom => ADDRESS
  464.  
  465. =over 4
  466.  
  467. The e-mail address which is used as sender.  By default,
  468. L<Mail::Util::mailaddress()|Mail::Util/"FUNCTIONS"> provides the address of the sender.
  469.  
  470. =back
  471.  
  472. . Port => INTEGER
  473.  
  474. =over 4
  475.  
  476. Port number to connect to on remote host
  477.  
  478. =back
  479.  
  480. . To => ADDRESSES
  481.  
  482. =back
  483.  
  484. $obj-E<gt>B<unescape_from>(())
  485.  
  486. =over 4
  487.  
  488. Remove the escaping added by L<escape_from()|Mail::Internet/"High-level functionality">.
  489.  
  490. =back
  491.  
  492. =head1 SEE ALSO
  493.  
  494. This module is part of the MailTools distribution,
  495. F<http://perl.overmeer.net/mailtools/>.
  496.  
  497. =head1 AUTHORS
  498.  
  499. The MailTools bundle was developed by Graham Barr.  Later, Mark
  500. Overmeer took over maintenance without development.
  501.  
  502. Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
  503. Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
  504. Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
  505. For other contributors see ChangeLog.
  506.  
  507. =head1 LICENSE
  508.  
  509. Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
  510. 2001-2007 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
  511.  
  512. This program is free software; you can redistribute it and/or modify it
  513. under the same terms as Perl itself.
  514. See F<http://www.perl.com/perl/misc/Artistic.html>
  515.  
  516.